(SST) ShlWAPI.pas Version 1.08
Developer Reference
(SST)ShlWAPI SHAnsiToAnsi Function
Copies the characters of an ANSI string into the provided buffer.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function SHAnsiToAnsi(pszSrc : LPCSTR; pszDst : LPSTR; cwchBuf : Integer) : Integer;  
Parameters
pszSrc [in] A pointer to the null-terminated ANSI string to copy.
pszDst [in/out] The address of, or a pointer to, the null-terminated buffer into which the function should write the copied, input string.
cwchBuf [in] The size, in number of characters, of the buffer specified in pszDst.
Return Values
If the function succeeds it returns the number of characters written to the buffer provided by the caller (i.e. the memory pointed to in pszDst). If the function fails it returns 0.
Remarks
SHAnsiToAnsi essentially performs the same task as does the Delphi SDK function StrCopy.
Unlike many other Windows, API functions, SHAnsiToAnsi does not return the required buffer size if zero (0) is specified in the cwchBuf parameter. Nor, does calling GetLastError() subsequently provide information on the cause for the failure.
If the function fails it is not possible to determine the exact cause for the error by calling the Windows API function GetLastError(), as this also returns 0 (NO_ERROR), even if null-pointers are passed to the function on call.
This function is exported by name as of ShlWAPI.dll version 6.0 under Vista, but according to the declaration and documentation in MS SDK version 6.1, it is available as of ShlWAPI.dll 5.0, under Windows 2000. Unfortunately, an ordinal by which function can be accessed in versions pre-dating Vista was not documented. Nonetheless, we were able to determine that the function is exported by ordinal 345 down to and including Windows NT 4.0 with Internet Explorer 5.0 and 98 SE with Internet Explorer 5.0.
Example
PROCEDURE TForm4.TestShlWAPISHAnsiToAnsi(Sender : TObject); //Support for function as ordinal 345 under Win 98 SE (with IE 5.0) confirmed !!! //Support for function as ordinal 345 under NT 4.0 with IE 5.0 confirmed !!! VAR srcansibuf : STRING; VAR srcstrlen : INTEGER; VAR destansibuf : ARRAY[0..64] OF CHAR; VAR destbufsize : INTEGER; VAR apiretval : INTEGER; VAR errorcode : INTEGER; VAR newinfoline : STRING; BEGIN srcansibuf := ''; srcstrlen := 0; FillChar(destansibuf, Length(destansibuf), #0); destbufsize := 0; apiretval := 0; errorcode := 0; //0 = NO_ERROR newinfoline := ''; SetLastError(NO_ERROR); //errorcode := INTEGER(GetLastError()); //uncomment to verify that the last error PRIOR to any function call is 0 srcansibuf := 'Hello ANSI to ANSI World'; srcstrlen := Length(srcansibuf); destbufsize := Length(destansibuf); newinfoline := 'SHAnsiToAnsi called with source string "' + srcansibuf + '" (length: ' + IntToStr(srcstrlen) + ') returned : '; //errorcode := INTEGER(GetLastError()); //uncomment to determine the last error prior to the function call SetLastError(NO_ERROR); apiretval := SHAnsiToAnsi(PChar(srcansibuf), destansibuf, destbufsize); //errorcode := INTEGER(GetLastError()); //uncomment to determine the last error after the function call IF apiretval > 0 THEN newinfoline := newinfoline + IntToStr(apiretval) + ' and in the dest buffer : "' + destansibuf + '"' ELSE BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' (the function call FAILED !), GetLastError returned : ' + IntToStr(errorcode); END; Memo1.Lines.Add(newinfoline); //errorcode := INTEGER(GetLastError()); //uncomment to determine the last error after the function call //Dest buffer length parameter set to 17 (too short by 7 character) FillChar(destansibuf, SizeOf(destansibuf), #0); destbufsize := 17; apiretval := 0; newinfoline := ''; errorcode := 0; newinfoline := 'SHAnsiToAnsi called with source string "' + srcansibuf + '" (length: ' + IntToStr(srcstrlen) + ') returned : '; SetLastError(NO_ERROR); //uncomment to ensure that the last error PRIOR to the function call is 0 apiretval := SHAnsiToAnsi(PChar(srcansibuf), destansibuf, destbufsize); //errorcode := INTEGER(GetLastError()); //uncomment to determine the last error after the function call IF apiretval > 0 THEN BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' and in the dest buffer : "' + destansibuf + '"'; Memo1.Lines.Add(newinfoline); newinfoline := 'and GetLastError returned : ' + IntToStr(errorcode); END ELSE BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' (the function call FAILED !), GetLastError returned : ' + IntToStr(errorcode); END; Memo1.Lines.Add(newinfoline); //Dest buffer length parameter set to 2 (too short by 23 characters) FillChar(destansibuf, SizeOf(destansibuf), #0); destbufsize := 2; apiretval := 0; newinfoline := ''; errorcode := 0; newinfoline := 'SHAnsiToAnsi called with source string "' + srcansibuf + '" (length: ' + IntToStr(srcstrlen) + ') returned : '; SetLastError(NO_ERROR); apiretval := SHAnsiToAnsi(PChar(srcansibuf), destansibuf, destbufsize); IF apiretval > 0 THEN BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' and in the dest buffer : "' + destansibuf + '"'; Memo1.Lines.Add(newinfoline); newinfoline := 'and GetLastError returned : ' + IntToStr(errorcode); END ELSE BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' (the function call FAILED !), GetLastError returned : ' + IntToStr(errorcode); END; Memo1.Lines.Add(newinfoline); //Dest buffer length parameter set to 1 (too short by 24 characters) FillChar(destansibuf, SizeOf(destansibuf), #0); destbufsize := 1; apiretval := 0; newinfoline := ''; errorcode := 0; newinfoline := 'SHAnsiToAnsi called with source string "' + srcansibuf + '" (length: ' + IntToStr(srcstrlen) + ') returned : '; SetLastError(NO_ERROR); apiretval := SHAnsiToAnsi(PChar(srcansibuf), destansibuf, destbufsize); IF apiretval > 0 THEN BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' and in the dest buffer : "' + destansibuf + '"'; Memo1.Lines.Add(newinfoline); newinfoline := 'and GetLastError returned : ' + IntToStr(errorcode); END ELSE BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' (the function call FAILED !), GetLastError returned : ' + IntToStr(errorcode); END; Memo1.Lines.Add(newinfoline); //Dest buffer length parameter set to 0 FillChar(destansibuf, SizeOf(destansibuf), #0); destbufsize := 0; apiretval := 0; newinfoline := ''; errorcode := 0; newinfoline := 'SHAnsiToAnsi called with source string "' + srcansibuf + '" (length: ' + IntToStr(srcstrlen) + ') returned : '; SetLastError(NO_ERROR); apiretval := SHAnsiToAnsi(PChar(srcansibuf), destansibuf, destbufsize); IF apiretval > 0 THEN newinfoline := newinfoline + IntToStr(apiretval) + ' and in the dest buffer : "' + destansibuf + '"' ELSE BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' (the function call FAILED !), GetLastError returned : ' + IntToStr(errorcode); END; Memo1.Lines.Add(newinfoline); //No dest buffer (pointer param set to NIL) //and buffer length parameter set to 0 FillChar(destansibuf, SizeOf(destansibuf), #0); destbufsize := 0; apiretval := 0; newinfoline := ''; errorcode := 0; newinfoline := 'SHAnsiToAnsi called with source string "' + srcansibuf + '" (length: ' + IntToStr(srcstrlen) + ') returned : '; SetLastError(NO_ERROR); apiretval := SHAnsiToAnsi(PChar(srcansibuf), NIL, 0); IF apiretval > 0 THEN newinfoline := newinfoline + IntToStr(apiretval) + ' and in the dest buffer : "' + destansibuf + '"' ELSE BEGIN errorcode := INTEGER(GetLastError()); newinfoline := newinfoline + IntToStr(apiretval) + ' (the function call FAILED !), GetLastError returned : ' + IntToStr(errorcode); END; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END;
When run under Windows Vista with SP 1 and IE 8, the above code produces the following output (note the last error(s) reurned by the Windows API function GetLastError when the function fails):
SHAnsiToAnsi called with source string "Hello ANSI to ANSI World" (length: 24) returned : 25 and in the dest buffer : "Hello ANSI to ANSI World" SHAnsiToAnsi called with source string "Hello ANSI to ANSI World" (length: 24) returned : 0 (the function call FAILED !), GetLastError returned : 0 SHAnsiToAnsi called with source string "Hello ANSI to ANSI World" (length: 24) returned : 0 (the function call FAILED !), GetLastError returned : 0 SHAnsiToAnsi called with source string "Hello ANSI to ANSI World" (length: 24) returned : 0 (the function call FAILED !), GetLastError returned : 0 SHAnsiToAnsi called with source string "Hello ANSI to ANSI World" (length: 24) returned : 0 (the function call FAILED !), GetLastError returned : 0 SHAnsiToAnsi called with source string "Hello ANSI to ANSI World" (length: 24) returned : 0 (the function call FAILED !), GetLastError returned : 0
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (SHAnsiToAnsi) function only.
Min. ShlWAPI.dll version according to MS SDK doc.: 5.0
Min. ShlWAPI.dll version based on SST research: 5.0
Min. OS version(s) according to Microsoft SDK doc.: Windows 2000, Windows 2000 Server, Windows Server 2003, Windows XP
Min. OS version(s) according to SST research.: Windows NT 4.0 with IE 5, Windows 98 SE with IE 5, Windows 2000, Windows XP, Windows Server 2003.
See Also
SHAnsiToUnicode, SHUnicodeToAnsi, SHUnicodeToUnicode, StrDup.
 
Windows APIs: SHAnsiToAnsi, SHAnsiToUnicode, SHUnicodeToAnsi, SHUnicodeToUnicode StrDup.


Document/Contents version 1.01
Page/URI last updated on 07.12.2023 		 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2022 		Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com